<?php declare(strict_types=1);

namespace Zyucv7\Components\AI\Common\Helpers;

/**
 * 提示词文本格式化工具类（PromptTextFormatter）
 * 作用：读取原始 txt 系统提示词，去掉换行，并进行 JSON 字符转义，生成可提交给 LLM API 的内容
 */
class PromptTextFormatter
{
	/**
	 * 从文件读取并格式化（formatFromFile）
	 * @param string $filePath txt 文件路径
	 * @param bool $asJsonLiteral 是否返回带引号的 JSON 字面量字符串（true 返回例如 "..."，false 返回去引号的已转义文本）
	 * @return string
	 * @throws \InvalidArgumentException
	 */
	public static function formatFromFile(string $filePath, bool $asJsonLiteral = false): string
	{
		$raw = self::readTextFile($filePath);
		return self::formatString($raw, $asJsonLiteral);
	}

	/**
	 * 读取 txt 文件（readTextFile）
	 * @param string $filePath
	 * @return string
	 * @throws \InvalidArgumentException
	 */
	public static function readTextFile(string $filePath): string
	{
		if (!is_file($filePath)) {
			throw new \InvalidArgumentException("文件不存在: {$filePath}");
		}
		$content = file_get_contents($filePath);
		if ($content === false) {
			throw new \InvalidArgumentException("无法读取文件: {$filePath}");
		}
		return $content;
	}

	/**
	 * 将文本去掉换行并进行 JSON 字符转义（formatString）
	 * @param string $text 原始文本
	 * @param bool $asJsonLiteral 是否返回带引号的 JSON 字面量字符串
	 * @return string
	 */
	public static function formatString(string $text, bool $asJsonLiteral = false): string
	{
		$withoutNewlines = self::removeNewlines($text);
		return $asJsonLiteral
			? self::toJsonLiteral($withoutNewlines)
			: self::jsonEscapeWithoutQuotes($withoutNewlines);
	}

	/**
	 * 去掉换行（removeNewlines）
	 * - 将 CRLF/CR/LF 统一替换为空格
	 * - 压缩多余空白为单个空格
	 * @param string $text
	 * @return string
	 */
	public static function removeNewlines(string $text): string
	{
		$normalized = str_replace(["\r\n", "\n", "\r"], ' ', $text);
		$normalized = preg_replace('/\s+/u', ' ', $normalized);
		return trim($normalized ?? '');
	}

	/**
	 * 转为 JSON 字面量（toJsonLiteral）
	 * - 返回带双引号的合法 JSON 字符串
	 * - 不转义中文与斜杠，便于可读
	 * @param string $text
	 * @return string
	 */
	public static function toJsonLiteral(string $text): string
	{
		$json = json_encode($text, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
		if ($json === false) {
			throw new \RuntimeException('JSON 编码失败');
		}
		return $json;
	}

	/**
	 * JSON 转义但不包含外围引号（jsonEscapeWithoutQuotes）
	 * - 适合手动拼装 JSON 时直接作为值内容（不含开头/结尾双引号）
	 * @param string $text
	 * @return string
	 */
	public static function jsonEscapeWithoutQuotes(string $text): string
	{
		$literal = self::toJsonLiteral($text);
		return substr($literal, 1, -1);
	}
} 